<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
 #
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 #
 # Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 #
 # The contents of this file are subject to the terms of either the GNU
 # General Public License Version 2 only ("GPL") or the Common Development
 # and Distribution License("CDDL") (collectively, the "License").  You
 # may not use this file except in compliance with the License. You can obtain
 # a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
 # or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
 # language governing permissions and limitations under the License.
 #
 # When distributing the software, include this License Header Notice in each
 # file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
 # Sun designates this particular file as subject to the "Classpath" exception
 # as provided by Sun in the GPL Version 2 section of the License file that
 # accompanied this code.  If applicable, add the following below the License
 # Header, with the fields enclosed by brackets [] replaced by your own
 # identifying information: "Portions Copyrighted [year]
 # [name of copyright owner]"
 #
 # Contributor(s):
 #
 # If you wish your version of this file to be governed by only the CDDL or
 # only the GPL Version 2, indicate your decision by adding "[Contributor]
 # elects to include this software in this distribution under the [CDDL or GPL
 # Version 2] license."  If you don't indicate a single choice of license, a
 # recipient has the option to distribute your version of this file under
 # either the CDDL, the GPL Version 2 or to extend the choice of license to
 # its licensees as provided above.  However, if you add GPL Version 2 code
 # and therefore, elected the GPL Version 2 license, then the option applies
 # only if the new code is made subject to such option by the copyright
 # holder.
 #

 -->
<html>
  <head>
    <title>Description of com.sun.enterprise.ee.cms.core package</title>
  </head>
  <body>
      <h1>Shoal GMS's core client API</h1>
      <hr>
      <p>Shoal's client API is provided in this package. The entry point for 
          clients using GMS is the <code>GMSFactory</code> class. This class 
          provides the APIs for getting a <code>GroupManagementService</code>
          instance for a given member name, group name, member type and 
          configuration. The <code>GroupManagementService</code>
          instance provides methods for registering interest in specific group 
          events. 
      </p>
      <p>To process group events on the client side, Shoal makes it easy for 
          clients by providing a single interface that needs to be implemented, 
          namely, the <code>CallBack</code> interface. This interface provides a
          method <code>processNotification()</code> that accepts a <code>Signal</code>
          object. Signals are of various types - each type corresponding to a 
          specific group event. Clients register interest in these events by 
          using <code>addActionFactory()</code> methods provided in 
          <code>GroupManagementService</code>. The clients pass in an instance 
      of a specific <code>ActionFactory</code> type to the method.</p>
      <p>The <code>ActionFactory</code> is a client side artifact with its 
      sub-types corresponding  to a specific group event. One can think of the 
      <code>ActionFactory</code>-<code>Action</code>-<code>Signal</code> triplet
as a set of one-to-one correspondence objects for a specific type of group event. 
Clients can choose to implement a specific <code>ActionFactory</code> and 
<code>Action</code> type or use the reference implementations provided in the 
    <code>com.sun.enterprise.ee.cms.impl.client</code> package.</p>
    
    <p>For instance, clients simply implement the CallBack interface and register 
        for group events using the default implementation of the, say, 
        <code>FailureNotificationActionFactory</code> to receive notifications for 
    failure events in the group.</p>
  </body>
</html>
